home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 2.toast / pc / sample code / networking / pgpuam / headers / clientuam.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-06-23  |  14.0 KB  |  453 lines
  1. /*
  2.      File:        ClientUAM.h
  3.  
  4.      Contains:    Public Header file for the AppleShare Client UAM API 
  5.  
  6.      Version:    3.8
  7.  
  8.      DRI:        Leland Wallace
  9.  
  10.      Copyright:    © 1997 by Apple Computer, Inc., all rights reserved.
  11.  
  12.      Warning:    *** APPLE INTERNAL USE ONLY ***
  13.                  This file may contain unreleased API's
  14.  
  15.      BuildInfo:    Built by:            Leland Wallace
  16.                  With Interfacer:    3.0d3   (PowerPC native)
  17.                  From:                ClientUAM.i
  18.                      Revision:        6
  19.                      Dated:            8/04/98
  20.                      Last change by:    law
  21.                      Last comment:    • changed the arg name from message to contextPtr in the
  22.  
  23.      Bugs:        Report bugs to Radar component "System Interfaces", "Latest"
  24.                  List the version information (from above) in the Problem Description.
  25.  
  26. */
  27. #ifndef __CLIENTUAM__
  28. #define __CLIENTUAM__
  29.  
  30. #ifndef __CONDITIONALMACROS__
  31. #include <ConditionalMacros.h>
  32. #endif
  33. #ifndef __MIXEDMODE__
  34. #include <MixedMode.h>
  35. #endif
  36. #ifndef __DEVICES__
  37. #include <Devices.h>
  38. #endif
  39. #ifndef __APPLETALK__
  40. #include <AppleTalk.h>
  41. #endif
  42. #ifndef __OPENTRANSPORT__
  43. #include <OpenTransport.h>
  44. #endif
  45. #ifndef __OPENTPTINTERNET__
  46. #include <OpenTptInternet.h>
  47. #endif
  48. #ifndef __OPENTPTAPPLETALK__
  49. #include <OpenTptAppleTalk.h>
  50. #endif
  51. #ifndef __ERRORS__
  52. #include <errors.h>
  53. #endif
  54. #ifndef __EVENTS__
  55. #include <Events.h>
  56. #endif
  57. #ifndef __APPLESHARE__
  58. #include <AppleShare.h>
  59. #endif
  60.  
  61.  
  62.  
  63. #if PRAGMA_ONCE
  64. #pragma once
  65. #endif
  66.  
  67. #ifdef __cplusplus
  68. extern "C" {
  69. #endif
  70.  
  71. #if PRAGMA_IMPORT
  72. #pragma import on
  73. #endif
  74.  
  75. #if PRAGMA_STRUCT_ALIGN
  76.     #pragma options align=mac68k
  77. #elif PRAGMA_STRUCT_PACKPUSH
  78.     #pragma pack(push, 2)
  79. #elif PRAGMA_STRUCT_PACK
  80.     #pragma pack(2)
  81. #endif
  82.  
  83.  
  84. /* Error values*/
  85.  
  86. enum {
  87.     kUAMError                    = -5002,                        /* afpBadUAM*/
  88.     kNotForUs                    = -50                            /* paramErr*/
  89. };
  90.  
  91. /* UAM Class & Type values*/
  92.  
  93. enum {
  94.     kUAMStdClass                = 0,                            /* Standard UAM (8 byte password)*/
  95.     kUAMVarClearClass            = 1,                            /* variable length cleartext password*/
  96.     kUAMVarCryptClass            = 2,                            /* variable length encrypted password*/
  97.     kUAMUserDefClass            = 3                                /* Custom UAM*/
  98. };
  99.  
  100.  
  101. enum {
  102.     kNoPasswd                    = 1,                            /* Class 0, No User Authentication (Guest)*/
  103.     kCleartextPasswd            = 2,                            /* Class 0, Cleartext password (8 byte password)*/
  104.     kEncryptPasswd                = 3,                            /* Class 0, RandnumExchange (8 byte password)*/
  105.     kVarPasswd                    = 4,                            /* Class 1, variable length cleartext password*/
  106.     kVarEncryptPasswd            = 5,                            /* Class 2, variable length encrypted password*/
  107.     kTwoWayEncryptPasswd        = 6                                /* Class 0, two way randnum exchange (8 byte password)*/
  108. };
  109.  
  110. /* general constants*/
  111.  
  112. enum {
  113.     kMaxAFPCommand                = 576,
  114.     kStdPWdLength                = 8,
  115.     kMaxPwdLength                = 64
  116. };
  117.  
  118.  
  119. /* UAM Commands    */
  120.  
  121. enum {
  122.     kUAMOpen                    = 0,
  123.     kUAMPWDlog                    = 1,
  124.     kUAMLogin                    = 2,
  125.     kUAMVSDlog                    = 3,
  126.     kUAMChgPassDlg                = 4,
  127.     kUAMChgPass                    = 5,
  128.     kUAMGetInfoSize                = 6,
  129.     kUAMGetInfo                    = 7,
  130.     kUAMClose                    = 8,
  131.     kUAMPrOpen                    = 9,
  132.     kUAMPrAuthDlog                = 10,
  133.     kUAMPrAuth                    = 11
  134. };
  135.  
  136.  
  137.  
  138. /* config bits*/
  139.  
  140. enum {
  141.     kUsePWDlog                    = 0,                            /* The UAM wants to put up its own Password/PRAuth Dialog*/
  142.     kUseVolDlog                    = 1,                            /* The UAM wants to put up its own Volume Selection DIalog*/
  143.     kSupportsCP                    = 2,                            /* The UAM supports Changing the password*/
  144.     kUseCPDlog                    = 3,                            /* The UAM wants to put up its own Change Password Dialog*/
  145.     kUseUAMInfo                    = 4                                /* The UAM supports storing authentication info in UAMInfo*/
  146. };
  147.  
  148. /* All other bits are reserved and must be set to 0*/
  149.  
  150.  
  151. /* structs*/
  152.  
  153.  
  154.  
  155. struct ClientInfo {
  156.     short                             fInfoType;                    /* the type of ClientInfo*/
  157.     Str255                             fDefaultUserName;            /* a pointer to the Default User name*/
  158. };
  159. typedef struct ClientInfo ClientInfo;
  160.  
  161.  
  162. enum {
  163.     kAFPClientInfo                = 0,
  164.     kPrClientInfo                = 1
  165. };
  166.  
  167. struct AFPClientInfo {
  168.     short                             fInfoType;                    /* the type of ClientInfo (kAFPClientInfo)*/
  169.     Str255                             fDefaultUserName;            /* a pointer to the Default User name*/
  170.     short                             fConfigFlags;                /* the hi  short of the gestalt('afpt') response*/
  171.     short                             fVersion;                    /* the low short of the gestalt('afpt') response*/
  172.     short                             fNumAFPVersions;            /* the number of afp versions supported by this client*/
  173.     StringPtr *                        fAFPVersionStrs;            /* an array of afp version strings supported by this client*/
  174. };
  175. typedef struct AFPClientInfo AFPClientInfo;
  176.  
  177. struct PRClientInfo {
  178.     short                             fInfoType;                    /* the type of ClientInfo (kPrClientInfo)*/
  179.     Str255                             fDefaultUserName;            /* a pointer to the Default User name*/
  180.     FSSpec                             fPPDFile;                    /* the fsspec of the ppd file for the currently selected printer*/
  181. };
  182. typedef struct PRClientInfo PRClientInfo;
  183.  
  184. /* Callbacks:*/
  185.  
  186. /*
  187.    this Completion routine is called with the contextPtr passed in to
  188.    the OpenAFPSession() and SendRequest() calls, when one of these calls
  189.    completes. The result parameter contains the AFP result.
  190.    You cannot call any of the callback routines from this Completion
  191.    routine, so you can't do chained completion routines. This routine
  192.    will be called just like any other completion routine or notifier
  193.    so the usual rules apply.
  194. */
  195.  
  196. typedef CALLBACK_API( void , CompletionPtr )(void *contextPtr, OSStatus result);
  197.  
  198. /*    GetClientInfo()
  199.     Returns information about the Client, such as which versions of AFP are
  200.     supported and the various gestalt values. This call also returns the
  201.     default user name. If the infoType is not avaliable it will return nil.
  202.  
  203.     pascal    OSStatus    GetClientInfo(short infoType,ClientInfo    **infoPtr);        
  204. */
  205. struct UAMMessage {
  206.     long                             commandCode;
  207.     short                             sessionRefNum;
  208.     OSStatus                         result;
  209.     unsigned char *                    cmdBuffer;
  210.     unsigned long                     cmdBufferSize;
  211.     unsigned char *                    replyBuffer;
  212.     unsigned long                     replyBufferSize;
  213.     CompletionPtr                     completion;
  214.     void *                            contextPtr;
  215.     UInt8                             scratch[80];                /* scratch space for the client*/
  216. };
  217. typedef struct UAMMessage UAMMessage;
  218.  
  219. typedef UAMMessage *                    UAMMessagePtr;
  220.  
  221. enum {
  222.                                                                 /* commandCodes (for future expansion)*/
  223.     kOpenSession                = FOUR_CHAR_CODE('UAOS'),
  224.     kSendRequest                = FOUR_CHAR_CODE('UASR')
  225. };
  226.  
  227. /*    OpenSession()
  228.     Opens a session to the specified address. If you are using AFP, cmdBuffer MUST 
  229.     contain an AFP Login command. If you are using AFP the command buffer size is limited
  230.     to kMaxAFPCommand (576 bytes). Set endpointString to nil if default is desired 
  231.     (TCP only, it is ignored for AppleTalk connections (and may also be ignored on
  232.     rhapsody)). Leave completion & contextPtr nil for sync. Session reference number 
  233.     is returned in the sessionRefNum field.
  234.  
  235.  
  236.     pascal    OSStatus    OpenSession(OTAddress *, const char* endpointString, UAMMessagePtr);
  237. */
  238. /*     SendRequest()
  239.     Sends a command to the server. If the session is an AFP session, cmdBuffer
  240.     MUST contain an AFP command. If you are using AFP the command buffer size is limited
  241.     to kMaxAFPCommand (576 bytes). Leave completion & contextPtr nil for sync.
  242.     the Session reference number for this connection must be in the sessionRefNum field.
  243.                 
  244.     pascal    OSStatus    SendRequest(UAMMessagePtr);
  245. */
  246.  
  247. /*    CloseSession()
  248.     Closes the session denoted by the sessRefNum;
  249.  
  250.     pascal    OSStatus    CloseSession(short sessRefNum);
  251. */
  252.  
  253. /*    SetMic()
  254.     Sets the message integrity code key. If the connection supports using 
  255.     keyed HMAC-SHA1 for message integrity, the UAM may pass a key down
  256.     to the network layer using this call. 
  257.  
  258.     pascal    OSStatus    SetMic(short sizeInBytes, Ptr micValue);
  259. */
  260. /*    EventCallback()
  261.     Call this fcn with any event that you do not handle in your FilterProc if you
  262.     put up a dialog. This passes the event back to the client so that update & idle
  263.     events are handled correctly. Returns true if the event was handled.
  264.  
  265.     pascal    Boolean        EventCallback(EventRecord *theEvent);
  266. */
  267. #if GENERATING68K
  268. typedef CALLBACK_API( OSStatus , OpenSessionPtr )(OTAddress *addr, const char *endpointString, UAMMessagePtr message);
  269. typedef CALLBACK_API( OSStatus , SendRequestPtr )(UAMMessagePtr message);
  270. typedef CALLBACK_API( OSStatus , CloseSessionPtr )(short sessRefNum);
  271. typedef CALLBACK_API( OSStatus , GetClientInfoPtr )(short infoType, ClientInfo **info);
  272. typedef CALLBACK_API( OSStatus , SetMicPtr )(short sizeInBytes, Ptr micValue);
  273. typedef CALLBACK_API( Boolean , EventCallbackPtr )(EventRecord *theEvent);
  274. #else
  275. typedef UniversalProcPtr                 OpenSessionPtr;
  276. typedef UniversalProcPtr                 SendRequestPtr;
  277. typedef UniversalProcPtr                 CloseSessionPtr;
  278. typedef UniversalProcPtr                 GetClientInfoPtr;
  279. typedef UniversalProcPtr                 SetMicPtr;
  280. typedef UniversalProcPtr                 EventCallbackPtr;
  281. #endif  /* GENERATING68K */
  282.  
  283. struct ClientUAMCallbackRec {
  284.     OpenSessionPtr                     OpenSessionUPP;
  285.     SendRequestPtr                     SendRequestUPP;
  286.     CloseSessionPtr                 CloseSessionUPP;
  287.     GetClientInfoPtr                 GetClientInfoUPP;
  288.     SetMicPtr                         SetMicUPP;
  289.     EventCallbackPtr                 EventCallbackUPP;
  290. };
  291. typedef struct ClientUAMCallbackRec ClientUAMCallbackRec;
  292.  
  293. struct VolListElem {
  294.     UInt8                             volFlags;                    /* volume flags*/
  295.     Str32                             volName;
  296. };
  297. typedef struct VolListElem VolListElem;
  298.  
  299. /* definitions for the volume flags*/
  300.  
  301. enum {
  302.     kMountFlag                    = 0,                            /* bit indicating this volume is to be mounted (set by the UAM)*/
  303.     kAlreadyMounted                = 1,                            /* bit indicating that the volume is currently mounted*/
  304.     kNoRights                    = 2,                            /* bit indicating that this user has no permission to use the volume*/
  305.     kHasVolPw                    = 7                                /* bit indicating that the volume has a volume password*/
  306. };
  307.  
  308. struct UAMOpenBlk {                                                /* called for UAMOpen & UAMPrOpen*/
  309.     StringPtr                         objectName;                    /* <-    server or printer name*/
  310.     StringPtr                         zoneName;                    /* <-    zone name or nil if no zone is present*/
  311.     OTAddress *                        srvrAddress;                /* <-    OT Address of the "server"    */
  312.     AFPSrvrInfo *                    srvrInfo;                    /* <-    for UAMOpen this is the GetStatus reply, for Printers ???*/
  313. };
  314. typedef struct UAMOpenBlk UAMOpenBlk;
  315.  
  316. struct UAMPWDlogBlk {                                            /* for the password dialog and prAuthDlog*/
  317.     StringPtr                         userName;                    /* <-    pointer to a Str64 containing the user name*/
  318.     unsigned char *                    password;                    /* <-    pointer to a Str64 containing the password*/
  319. };
  320. typedef struct UAMPWDlogBlk UAMPWDlogBlk;
  321.  
  322. struct UAMAuthBlk {                                                /* called for login and prAuthenticate*/
  323.     StringPtr                         userName;                    /* <-    pointer to a Str64 containing the user name*/
  324.     unsigned char *                    password;                    /* <-    pointer to a 64 byte buffer containing the password*/
  325.     OTAddress *                        srvrAddress;                /* <-    OT Address of the "server"    */
  326. };
  327. typedef struct UAMAuthBlk UAMAuthBlk;
  328.  
  329. struct UAMVSDlogBlk {                                            /* for the volume select dialog*/
  330.     short                             numVolumes;                    /* <-    number of volumes in the volume list*/
  331.     VolListElem *                    volumes;                    /* <-    the volume list*/
  332. };
  333. typedef struct UAMVSDlogBlk UAMVSDlogBlk;
  334.  
  335. struct UAMChgPassBlk {                                            /* for both the change password dialog and the change password call*/
  336.     StringPtr                         userName;                    /* <-    pointer to a Str64 containing the user name*/
  337.     unsigned char *                    oldPass;                    /* <-    pointer to a 64 byte buffer containing the old password*/
  338.     unsigned char *                    newPass;                    /* <-    pointer to a 64 byte buffer containing the new password*/
  339. };
  340. typedef struct UAMChgPassBlk UAMChgPassBlk;
  341.  
  342. struct UAMArgs {
  343.     short                             command;                    /* <-    UAM command selector*/
  344.     short                             sessionRefNum;                /* <->    session reference number*/
  345.     long                             result;                        /*  ->    command result*/
  346.     void *                            uamInfo;                    /* <-    pointer to a block of Auth Data*/
  347.     long                             uamInfoSize;                /* <->    size of the Auth Data*/
  348.     ClientUAMCallbackRec *            callbacks;                    /* <-    Callback record */
  349.     union {
  350.         UAMChgPassBlk                     chgPass;
  351.         UAMVSDlogBlk                     vsDlog;
  352.         UAMAuthBlk                         auth;
  353.         UAMPWDlogBlk                     pwDlg;
  354.         UAMOpenBlk                         open;
  355.     }                                 Opt;
  356. };
  357. typedef struct UAMArgs UAMArgs;
  358.  
  359. EXTERN_API( OSStatus )
  360. UAMCall                            (UAMArgs *                theArgs);
  361.  
  362.  
  363.  
  364. /* procinfos*/
  365.  
  366. enum {
  367.     kOpenSessionProcInfo = kPascalStackBased    
  368.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  369.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(OTAddress *)))        
  370.             | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(const char*)))        
  371.             | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(UAMMessagePtr))),        
  372.     
  373.     kSendRequestProcInfo =  kPascalStackBased    
  374.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  375.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(UAMMessagePtr))),        
  376.     
  377.     kCloseSessionProcInfo =  kPascalStackBased    
  378.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  379.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short))),                
  380.     
  381.     kGetClientInfoProcInfo =  kPascalStackBased    
  382.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  383.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short)))    
  384.             | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(ClientInfo **))),        
  385.     
  386.     kSetMicProcInfo =  kPascalStackBased    
  387.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  388.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short)))                
  389.             | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Ptr))),                
  390.     
  391.     kEventCallbackProcInfo =  kPascalStackBased    
  392.             | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))    
  393.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(EventRecord *))),        
  394.     
  395.     kUAMCallProcInfo =  kPascalStackBased
  396.             | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))    
  397.             | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(UAMArgs *)))            
  398. };
  399.  
  400. /* Resouce definitions
  401. */
  402.  
  403. enum {
  404.     kUAMName                    = 0,                            /* user visible name of the UAM*/
  405.     kUAMProtoName                = 1,                            /* protocol name of the UAM (sent to the server in the login cmd)*/
  406.     kUAMDescription                = 2,                            /* short description of the UAM (displayed in the dialog)*/
  407.     kUAMHelpBalloon                = 3                                /* Str255 for the Balloon Help item*/
  408. };
  409.  
  410.  
  411. enum {
  412.     kUAMFileType                = FOUR_CHAR_CODE('uams')        /* Type of the UAM file*/
  413. };
  414.  
  415. /* resource types*/
  416.  
  417. enum {
  418.     kUAMStr                        = FOUR_CHAR_CODE('uamn'),
  419.     kUAMCode                    = FOUR_CHAR_CODE('uamc'),
  420.     kUAMConfig                    = FOUR_CHAR_CODE('uamg')
  421. };
  422.  
  423. /* 'uams' resource IDs    */
  424.  
  425. enum {
  426.     kUAMTitle                    = 0,                            /* UAM Title string (shown in the UAM list)*/
  427.     kUAMProtocol                = 1,                            /* UAM protocol name*/
  428.     kUAMPWStr                    = 2,                            /* UAM description string (shown in the Password dialog)*/
  429.     kUAMBallHelp                = 3                                /* Balloon Help string for the Password dialog.*/
  430. };
  431.  
  432.  
  433. #if PRAGMA_STRUCT_ALIGN
  434.     #pragma options align=reset
  435. #elif PRAGMA_STRUCT_PACKPUSH
  436.     #pragma pack(pop)
  437. #elif PRAGMA_STRUCT_PACK
  438.     #pragma pack()
  439. #endif
  440.  
  441. #ifdef PRAGMA_IMPORT_OFF
  442. #pragma import off
  443. #elif PRAGMA_IMPORT
  444. #pragma import reset
  445. #endif
  446.  
  447. #ifdef __cplusplus
  448. }
  449. #endif
  450.  
  451. #endif /* __CLIENTUAM__ */
  452.  
  453.